Help me help you

Brief references for navigating jungles .rmd format variations

1 Motivation

“Hi, yes, I have a greivance I would like to file:
I signed up to use R not yaml, css, js, bib, markdown, html, and grep.”

— Nick Spyrison, 2018. Loosely transcribed

Suffice it to say that it took and still takes me agrivating amounts of time just to get a new .rmd format compiling, let alone polish options and sizes. I am writing this blog and corisponding repo to allay such frustrations for my future self and hopefuly some others as well.

with R Markdown formating

I must respond with something slightly cliche, use the right tool for the right job. Problems and tools come in all shapes and sizes. While frustrating at times, these frictions are the right of passage we undergo to achieve a rich diversity and quality of formats. We should also note that they exist for completely valid reasons considering the sometimes nebulous complexity of the moving pieces between code and its output. This document focuses on formats and nuances of using R mark down files (.rmd), which stems primarily from the work of Yihui Xie, many thanks Yihui. I attempt to mitigate friction by providing text and directory examples.

2 Static documents: references, figures, and figure captions .pdf

Scope: Static .pdf documents compiled with the bookdown::pdf_document2 format.

Requires:
— in YAML header:
output: bookdown::pdf_document2 ### pdf_document2 changes how fig references work to /ref()
bibliography: bib_example.bib ### Allows bibliography references
— in directory:
./figures/<all figures and images being used>
./<myBibliographyFile.bib>

• A .bib reference, (Matejka and Fitzmaurice 2017), is made with [@matejka_same_2017].
  • Find bib tags at the top of each entry in your .bib file.
• A Section reference reference is made with[Section reference](#sec:rmdRef)
  • Given that you taged your .rmd header by adding {#sec:rmdRef} after the header text.
  • The prefix ‘sec:’ is not magical, but is an advisable habit to adopt for organization.
  • Alternatively, section with \ref{sec:rmdRef} should create a hyperlinked number for the section. (no ‘#’ in ‘#sec’ and no ‘@’ in \@ref{} as found in some other formats).
• A figure reference is made with \ref(fig:doge) (no ‘@’; in \@ref(fig:doge) as found in some other formats).
  • Note: the prefix ‘fig:’ is not automatically added to the name of the R chunk, ‘doge’ in this case.

A figure caption: wow, such figure, much caption.

(ref:thisIsDog-cap) A figure capation made outside of an R chunk arguments. Good for when you do fancy formating or inline \(\LaTeX\) code. Apparently not compatible with ‘html_document’.

(ref:thisIsDog-cap)

---

3 Slides (.html): a crash course on using xaringan

Scope: Presentation slides (.html) produced with xaringan::moon_reader.

Requires:
— in YAML:
output: xaringan::moon_reader

• Use — to create a new slide, provided that it’s followed by
• Any # header (of any level) becomes the the slide title.
• Bullets: top level are made with '- ', the space is important.
  • Following levels needs indentation of 4 spaces (2 tabs by default), ie. ' - '
• Use -- to create an incremental slide break, hiding later content
• Xaringan is very sensitive to white space, when in doubt make sure newslides, titles, and content.
• Xaringan is sensitive to comments; use <!-- <comment> --> with caution!

4 Basic formating your slides using .css files

Scope: Presentation slides (.html) produced with xaringan::moon_reader.

Requires:
— in YAML:
output:
\(\:\:\)xaringan::moon_reader:
\(\:\:\:\:\)css:
\(\:\:\:\:\:\:\)- ninjutsu ### or your next favorite .css file, like: # - "assets/xaringan-themer.css"
\(\:\:\:\:\:\:\)- "assets/custom.css"
— in directory:
./assets/<All .css files used>

• Call .css .funtions[], by nesting content inside, with '.functionNm[', and ']' each on their own line:

.pull-left[
Creates a left column...
]
.pull-right[
... and a right column respectively.
]

• Create your own .css functions in ./assests/custom.css, for instance:

/* create your own .css functions, like there for changing body text:*/
.larger {font-size: 140%}
.large {font-size: 120%}
.small {font-size: 80% }
.smaller {font-size: 60% }

• You can do some neat stuff with nest relative fucntions.

---

5 Wrap up

Thanks for the read. Let me know if this helped, or if there are other topics you need need help getting started wih. Drop me a line by email at spyrison@gmail.com.

6 PS: Code hygene / formating

A bit off topic, but it bears repeating. Practice good code hygene. If you arn’t yet familiar with this term it doubly applies to you. I suggest reading the Tidyverse Style Guide most of it may seem pedantic, but they are listed for a reason. Not everything will be equally important based on the size of you file, directory, and number of collaborators, but it’s better to form good habits early.

I strongly, strongly suggest at least:

• Proper code indentation and nesting!!!!__
  • When in doubt, use the hotkey for intenting (Cntl + i) on the current line or selection.
• Keep each line to 80 characters
  • ‘Show margin (Margin column 80)’: RStudio > Tools > Global Options... > Code > Display > Show margin [x]
  • This lets you know when your lines are too long
  • Ensures you leave yourself (and others) realestate for another pane.
• Assignment:
  • Use ‘<-’ rather than ‘=’ ie. use a <- 5, not a = 5
  • Use left-handed assignment ie. use a <- 5, not 5 -> a
• Structure:
  • Use ‘Show document outline (Ctrl + Shift + O)’; button in the top right of the file pane, looks like indented lines.
  • In .r files: create outline references by ending a comment with 4 or more trailing ‘-’ ie. # Initialize vars -----
  • In .rmd files: create outline references using header and heder levels ie. # Introduction … ## Motivation

Matejka, Justin, and George Fitzmaurice. 2017. “Same Stats, Different Graphs: Generating Datasets with Varied Appearance and Identical Statistics Through Simulated Annealing.” In Proceedings of the 2017 CHI Conference on Human Factors in Computing Systems - CHI ’17, 1290–4. Denver, Colorado, USA: ACM Press. https://doi.org/10.1145/3025453.3025912.